home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 49 / Amiga Format CD49 (2000-01-17)(Future Publishing)(GB)(Track 1 of 3)[!][issue 2000-02].iso / -serious- / misc / dislib / autodocs / disassembler.doc
Text File  |  1999-11-29  |  6KB  |  163 lines
  1. TABLE OF CONTENTS
  2.  
  3. disassembler.library/--Background--
  4. disassembler.library/Disassemble
  5. disassembler.library/FindStartPosition
  6.  
  7. disassembler.library/--Background--        disassembler.library/--Background--
  8.  
  9.     PURPOSE
  10.  
  11.         The purpose of this library is to provide an easy to use and 
  12.         powerful disassembler. It knows all MC68K processors starting with 
  13.         the 68000 up to the 68060, FPU and MMU instructions.
  14.  
  15.         The code is MMU aware, i.e. won't try to access invalid or 
  16.         non-available memory, and makes use of the mmu.library if it is 
  17.         available. It will even work without the library, but it won't be 
  18.         able to validate its accesses and might, therefore, access invalid 
  19.         memory if the addresses passed in are incorrect.
  20.  
  21.         The library functions are interrupt and supervisor callable, 
  22.         provided your functions - and the PutProc function passed in - is.
  23.  
  24. disassembler.library/Disassemble        disassembler.library/Disassemble
  25.  
  26.     NAME
  27.         Disassemble        -    disassemble MC68K object code to assembler
  28.  
  29.     SYNOPSIS
  30.         nextpc = Disassemble ( disdata );
  31.         d0                        a0
  32.  
  33.         APTR Disassemble ( struct DisData * );
  34.  
  35.     FUNCTION
  36.         Disassembles the memory between the ds_From and ds_Upto fields
  37.         writing the disassembled data out using the ds_PutProc function.
  38.         The PC position is marked by a "*".
  39.  
  40.     INPUTS
  41.         disdata        -    A structure specifying the details of the request.
  42.                         It has to be filled out like the following:
  43.  
  44.         struct DisData {
  45.             APTR            ds_From;        
  46.             APTR            ds_UpTo;    
  47.             APTR            ds_PC;      
  48.             void           *ds_PutProc; 
  49.             APTR            ds_UserData;
  50.             APTR            ds_UserBase;   
  51.             UWORD           ds_Truncate;    
  52.             UWORD           ds_reserved;   
  53.         };
  54.  
  55.         ds_From is the memory location to start the disassembly from. This 
  56.         *MUST* be an even address.
  57.         ds_UpTo is the (exclusive) end of the memroy region to disassemble.
  58.  
  59.         ds_PC is a special address which is marked by an asterisk ("*") on
  60.         disassembly. This feature can be used to mark the position of the
  61.         PC.
  62.  
  63.         void *PutProc is actually a function pointer. It is not declared as
  64.         such to avoid unnecessary casting between compilers. Your code is
  65.         called like this:
  66.  
  67.         register d0    -    the ASCII code to print. Line ends are marked with a
  68.                         single line feed LF = 0x0a.
  69.         register a1    -     the contents of the ds_UserData field of the structure
  70.                         above.
  71.         register a3 -     ditto.
  72.         register a4 -    the contents of ds_UserBase. This is most useful for
  73.                         passing the pointer to the data space when using C or
  74.                         other high level languages.
  75.  
  76.         On exit, the routine may pass an updated a3 register back to the 
  77.         library which will be passed in a1 and a3 next time, similar to
  78.         the exec RawDoFmt() function.
  79.  
  80.         ds_UserData is the contents of registers a1 and a3 upon calling your
  81.         routine. They are for your private use.
  82.  
  83.         ds_UserBase is loaded to register a4 before calling the put procedure.
  84.         Should be setup to be the _LinkerDB if the near data model is used.
  85.  
  86.         ds_Truncate is the maximal line length to output. If this field is,
  87.         for example, set to 80, longer lines will be truncated by the library
  88.         to fit on the screen. If set to zero, no truncation takes place.
  89.  
  90.         ds_reserved must be set to zero to support future extensions.
  91.  
  92.  
  93.     RESULTS
  94.         an updated pointer where the disassembly stopped. If you pass this
  95.         pointer back in as "ds_From", the disassembler will automatically
  96.         continue at the right place.
  97.  
  98.     NOTES
  99.         this call will make use of the mmu.libary if available. It won't
  100.         access illegal memory or I/O space, provided the mmu table is
  101.         setup correctly.
  102.  
  103.         This routine is interrupt and supervisor callable, provided your
  104.         provided bs_PutProc is. This makes this library function ideal for
  105.         debugging tools and monitors.
  106.  
  107.     BUGS
  108.  
  109.     SEE ALSO
  110.         exec.library/RawDoFmt(), libraries/disassembler.h
  111.  
  112. disassembler.library/FindStartPosition    disassembler.library/FindStartPosition
  113.  
  114.     NAME
  115.         FindStartPosition    -    find an anchor point for disassembly
  116.  
  117.     SYNOPSIS
  118.         start = FindStartPosition ( pc , min , max );
  119.         d0                            a0     d0       d1
  120.  
  121.         APTR FindStartPosition ( APTR , UWORD min , UWORD max );
  122.  
  123.     FUNCTION
  124.         Given a PC address, this routine tries to find a useable address
  125.         to start the disassembly from, in a way that the PC address is
  126.         correctly included in the disassembly and that no, or as few illegal
  127.         instructions as possible show up. The code in front of the PC is
  128.         investigated, and a location between pc-min and pc-max is
  129.         returned, with min<max. If no suitable address was found, the pc
  130.         passed in is returned.
  131.  
  132.         This makes this function an "go backwards" disassembly tool. This 
  133.         is usually problematic due to the CISC design of the MC68K, namely
  134.         having instructions of various lengths.
  135.  
  136.     INPUTS
  137.         pc        -    the anchor point. This is supposed to be known to be a
  138.                     valid address with a valid instruction. This instruction
  139.                     is guaranteed to show up in a disassembly started at the
  140.                     resulting address.
  141.         min        -    the minimum distance from the PC to start the search.
  142.                     Note that this must be postive, it will be subtracted
  143.                     from the "pc".
  144.         max        -    the maximal distance where the search will stop. This is
  145.                     again a positive number.
  146.  
  147.     RESULTS
  148.         An address between pc-max and pc-min which, when used as start
  149.         address for Disassemble(), will make the requested "pc" instruction
  150.         part of the output stream.
  151.  
  152.     NOTES
  153.         The purpose of this function is to find an anchor point for 
  154.         disassembling code "around" a given location. Use, as first step,
  155.         the desired location to this procedure, then start disassembling
  156.         at the result, using about max*2 bytes.
  157.  
  158.     BUGS
  159.  
  160.     SEE ALSO
  161.         Disassemble(), libraries/disassembler.h
  162.  
  163.